DOC: Extended the documentation for DataFrame.sort_values()
#57678
Conversation
…rther explain the single-column vs. multi-column sorting; added further explanation and simplification for customized sorting, e.g, using `natsort` package
There was a problem hiding this comment.
Thanks for improving this docstring @aallahyar. Your changes look great, but while reviewing I spotted an error in an example in the original docstring. If you want to fix it, that would be amazing.
Also, for next time, it's in general better to use a branch to open PRs. If you only contribute this PR it shouldn't make a difference, but if you open a second PR to pandas, things will become wild with git (changes here will be mixed with the new PR...).
pandas/core/frame.py
Outdated
| @@ -6891,6 +6913,8 @@ def sort_values( | |||
| 3 48hr 40 | |||
| 4 96hr 50 | |||
| >>> from natsort import index_natsorted | |||
| >>> index_natsorted(df["time"]) | |||
| [0, 3, 2, 4, 1] | |||
| >>> df.sort_values( | |||
| ... by="time", key=lambda x: np.argsort(index_natsorted(df["time"])) | |||
There was a problem hiding this comment.
This example seems wrong. The df["time"] inside of the lambda should be the x received as the parameter. Do you mind updating it since you are improving this docstring?
|
/preview |
|
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/57678/ |
|
The rendered version of the changes here is available here, in case it's useful. |
|
Thanks @datapythonista for reviewing the update! Would be happy to fix the issue. Please take a look. Also thank you for the guidance! |
|
@datapythonista could you please let me know if any other modification is needed for this PR? Thanks :) |
There was a problem hiding this comment.
Thanks a lot for the work on this @aallahyar very nice. Looks perfect now (I'll let a second core dev have a look before merging).
|
Thanks @aallahyar |
…-dev#57678) * DOC:extended the documentation for `pandas.DataFrame.sort_values`; further explain the single-column vs. multi-column sorting; added further explanation and simplification for customized sorting, e.g, using `natsort` package * shortened the added dostrings to 80 columns; fixed a typo * added another `shell` line to avoid `micromamba` test failure * fixed a typo in a `DataFrame.sort_values()` example * added a warning to raise awareness about a potential issue with `natsort` * simplified the examples * added a single example about `natsort`
The current docstring for
DataFrame.sort_values()is lacking clarity, and also contains links that are not converted to hyperlinks. I extended and rephrased part of the documentation for this method. In particular:keyargument,natsortexample, with added explanation.